After auditing PR #141 (parallel Codex run for REMOTE-1777), extend the
sweep to the files that still said 'team API key' in places where the
phrase should also acknowledge agent identity / Default Service Account
keys created in the Oz web app. The Warp desktop app continues to label
its key type 'Team' (and Jason is reverting NamedAgents in the client
so it stays that way), so the wording becomes 'team or agent API key'
rather than a pure rename.

Touched files:
- agent-platform/cloud-agents/agents.mdx
- agent-platform/cloud-agents/team-access-billing-and-identity.mdx
- agent-platform/cloud-agents/environments.mdx
- agent-platform/cloud-agents/quickstart.mdx
- agent-platform/cloud-agents/self-hosting/reference.mdx
- enterprise/team-management/admin-panel.mdx
- enterprise/support-and-resources/billing.mdx
- reference/cli/integration-setup.mdx
- reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx
- reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx
- support-and-community/plans-and-billing/credits.mdx
- support-and-community/plans-and-billing/add-on-credits.mdx
- support-and-community/plans-and-billing/pricing-faqs.mdx

agents.mdx also gains the explicit 'Default Service Account' callout
and the Warp-app-Team / Oz-web-app-Agent equivalence note.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Document Personal / Team / Agent API key types

The Oz web app at oz.warp.dev/settings now uses 'Agent' API keys bound
to a specific agent identity, while the Warp desktop app still shows
'Team' (an Agent key bound to the team's Default Service Account is
functionally identical to a Team key for headless workflows).

Updates:
- reference/cli/api-keys.mdx: rewrite to cover all three key types,
  describe per-surface UI (Oz web app vs. Warp desktop app), and call
  out the Default Service Account / Team-key equivalence.
- Self-hosting prereqs (managed-{docker,kubernetes,direct}, quickstart,
  unmanaged), integrations/quickstart-github-actions, api-and-sdk/
  quickstart, reference/cli/quickstart: update 'create a team API key'
  wording to mention both surfaces and link the new key-types section.
- integrations/github-actions.mdx: replace broken /reference/cli/
  #generating-api-keys anchor with /reference/cli/api-keys/.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Broaden API key wording across billing, GitHub auth, and error docs

After auditing PR #141 (parallel Codex run for REMOTE-1777), extend the
sweep to the files that still said 'team API key' in places where the
phrase should also acknowledge agent identity / Default Service Account
keys created in the Oz web app. The Warp desktop app continues to label
its key type 'Team' (and Jason is reverting NamedAgents in the client
so it stays that way), so the wording becomes 'team or agent API key'
rather than a pure rename.

Touched files:
- agent-platform/cloud-agents/agents.mdx
- agent-platform/cloud-agents/team-access-billing-and-identity.mdx
- agent-platform/cloud-agents/environments.mdx
- agent-platform/cloud-agents/quickstart.mdx
- agent-platform/cloud-agents/self-hosting/reference.mdx
- enterprise/team-management/admin-panel.mdx
- enterprise/support-and-resources/billing.mdx
- reference/cli/integration-setup.mdx
- reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx
- reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx
- support-and-community/plans-and-billing/credits.mdx
- support-and-community/plans-and-billing/add-on-credits.mdx
- support-and-community/plans-and-billing/pricing-faqs.mdx

agents.mdx also gains the explicit 'Default Service Account' callout
and the Warp-app-Team / Oz-web-app-Agent equivalence note.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Final pass: normalize key-type casing, remove redundant Enterprise sentence

After a final review, polish the wording for consistency:

- Lowercase 'team API key' / 'agent API key' in prose (the concept).
  Reserve **bold** for the literal UI labels (Personal / Team / Agent).
  This matches how 'personal API key' was already styled.
- Self-hosting prereqs: switch (`Agent` type) / (`Team` type) backticks
  to (**Agent** type) / (**Team** type) since these are UI labels per the
  style guide, not literal code/strings.
- agents.mdx: 'called **Default Service Account**' → backticks, to match
  every other reference to the identity name in this PR.
- team-access-billing-and-identity.mdx line 85: drop a redundant
  'On Enterprise plans, these runs draw from the team-scoped credit
  pool...' sentence I had accidentally added to the Build/Max/Business
  bullet — that case is already covered by the Enterprise bullet right
  below it, and the GitHub-auth note duplicates content from the
  dedicated 'Team GitHub authorization' section.
- api-keys.mdx 'Deleting API keys' wording: 'find it in either surface'
  was ambiguous; spell it out as 'either the Oz web app or the Warp
  desktop app's API Keys list'.

No structural changes — pure textual edits, build behavior unchanged.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Switch to 'agent API key' throughout, with single team\u2192agent disclaimer

Per user feedback: stop dual-naming (team or agent API key) and just use
'agent API key' everywhere. Add a single, prominent disclaimer at the
top of api-keys.mdx noting that 'agent' used to be called 'team' and
that the two behave identically.

api-keys.mdx restructured:
- Top of page: new :::note 'Naming change' disclaimer that explains the
  team \u2192 agent rename, the Default Service Account equivalence, and
  notes the Warp desktop app may still label the toggle 'Team'.
- 'API key types' section: now lists only Personal and Agent (Team
  folded into Agent with the legacy-key note).
- 'Creating API keys > From the Warp desktop app': simplified to a
  single step that says pick Personal, Agent, or Team; pointers back
  to the disclaimer for details.\n- Best practices and Managing sections: 'team or agent keys' \u2192\n  'agent keys'.\n\nAll other affected files: 'team or agent API key' / 'team and agent\nAPI key' / pre-existing 'team API key' \u2192 'agent API key'. The legacy\nterm only survives in:\n- The api-keys.mdx disclaimer.\n- One parenthetical in team-access-billing-and-identity.mdx that\n  explicitly explains the legacy term for users who see it in the\n  Warp desktop app.\n- analytics-api.mdx now says 'Agent API keys (including legacy team\n  keys) are explicitly rejected'.\n- A historical changelog entry.\n\nCo-Authored-By: Oz <oz-agent@warp.dev>

* Reframe agent API key docs around agent identities

Restructure the API keys page (reference/cli/api-keys.mdx) so it reads
as a principal-first conceptual page:

- Open with 'Principals: personal or agent' instead of leading with
  the legacy naming-change disclaimer.
- Add 'Agent identities power agent API keys' with concrete worked
  examples (deploy-bot, pr-reviewer, nightly-jobs) that show how
  binding a key to an identity scopes its secrets, skills, and
  attribution.
- Add 'The Default Service Account' as the no-config baseline, and
  house the legacy 'team API key' note there as an inline callout.
- Split 'Creating an API key' into Oz web app (recommended, only
  surface that exposes the named-identity picker) and Warp desktop
  app (binds agent keys to the Default Service Account).
- Reframe billing and GitHub-authorization around the principal.

Strengthen agents.mdx (the agent-identity concept page):

- Add an IAM-service-account mental model paragraph.
- Strengthen the value-prop bullets with concrete deploy-bot /
  pr-reviewer / nightly-jobs examples.
- Add 'Quickstart: create a custom agent identity' (5 steps:
  create secret, POST /api/v1/agent/identities, generate bound key,
  run agent, confirm attribution in the dashboard).
- Add a short 'Agent API keys' subsection cross-linking to
  api-keys.mdx and naming the legacy 'team API key' equivalence.

Tighten the other affected docs so they defer to api-keys.mdx for
the personal-vs-agent guidance instead of repeating per-line
'Warp desktop app's equivalent toggle may still show Team' notes:

- self-hosting/{quickstart,managed-{docker,kubernetes,direct},
  unmanaged}.mdx prereqs collapse to 'Create an agent API key in
  the Oz web app bound to the Default Service Account (or a custom
  agent identity for workflow-scoped attribution).'
- team-access-billing-and-identity.mdx GitHub-auth section
  attributes commits to the bound agent identity (or to the
  Default Service Account for legacy team keys).
- integrations/github-actions.mdx, integrations/quickstart-github-actions.mdx,
  reference/api-and-sdk/quickstart.mdx, reference/cli/quickstart.mdx
  shorten inline notes to point at api-keys.mdx and link agents.mdx.
- unmanaged.mdx: wrap the oz agent run CLI command in backticks in
  the description so it reads as a literal command (also clears the
  OZ-TERM style lint warning).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Disentangle GitHub-side commit attribution from Oz-side run identity

Addresses oz-for-oss review on PR #143 (discussion r3307282172): the
docs incorrectly claimed that PRs and commits opened via the Oz by
Warp GitHub App were attributed to the bound agent identity. In
reality:

- On GitHub, commits and pull requests opened with a GitHub App
  installation token are attributed to the Oz by Warp GitHub App's
  bot user — not to the agent identity the API key is bound to.
- The agent identity is the Oz-side run identity. It controls run
  filtering, audit attribution, and which secrets/skills the run
  inherits — but it does not appear as a commit author on GitHub.

Fix the three places that had the conflation:

- team-access-billing-and-identity.mdx "Setting up team GitHub
  authorization" step 3 (line 143).
- team-access-billing-and-identity.mdx "Personal tokens vs. GitHub
  App tokens" bullet (line 159).
- reference/cli/api-keys.mdx "Billing and GitHub authorization"
  agent-keys paragraph (line 82).

Each now explicitly separates 'on GitHub, the GitHub App is the
author' from 'in the Oz dashboard, the agent identity is the run
attribution'.

The companion SUGGESTION (r3307282159) about the billing bullet at
team-access-billing-and-identity.mdx line 85 was already addressed
by the earlier restructure commit 51ea888 — that bullet no longer
duplicates the Enterprise sentence or mixes GitHub authorization
into the billing-focused list. The 'Team or' prefix in the
reviewer's suggested wording is intentionally not adopted, because
the restructure unifies the terminology under 'agent API key'
(with the legacy 'team API key' equivalence covered once in
api-keys.mdx#the-default-service-account).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Replace 'headless' / 'workflow-scoped' jargon with plain 'automated'

Per feedback that 'workflow-scoped identity for headless runs' is
hard to parse, sweep the PR's affected files and replace jargon
with plain-English equivalents:

- 'workflow-scoped identity for headless runs' \u2192 'automated runs
  (no specific user behind them)' or 'automated runs' depending
  on context.
- 'headless run / workflow / caller / automation' \u2192 'automated
  run / workflow / caller'.
- 'workflow-scoped attribution' \u2192 'so runs are attributed to a
  specific bot'.

Files touched: integrations/github-actions.mdx,
integrations/quickstart-github-actions.mdx, reference/cli/api-keys.mdx
(Principals, Default Service Account, Creating an API key from the
Oz web app, Best practices), agents.mdx (mental-model paragraph,
How agent identities work, Agent API keys, Running as an agent
identity), reference/api-and-sdk/quickstart.mdx,
self-hosting/unmanaged.mdx, team-access-billing-and-identity.mdx
(credit usage bullet).

Kept the industry-standard term 'headless servers' in the
api-keys.mdx opening line (CI pipelines, headless servers, VMs,
Codespaces) since that's a well-understood compound term.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Senior copywriter pass: rename to 'cloud agents', drop Default Service Account, fix principal differentiation

Address user feedback on the prior framing:

1. "agent identity" sounds abstract; just call them cloud agents
2. "Default Service Account" is an internal implementation detail
3. "(no specific user behind them)" is an awkward way to differentiate

Major rewrites:

agents.mdx — Rename to 'Agents'. Drop the IAM service account
analogy. Open with what a cloud agent is and what binding a key
to it gets you. Replace every 'agent identity'/'identities'
with 'cloud agent'/'cloud agents' (or just 'agent' when
unambiguous). Drop standalone 'Default Service Account'
mentions; the team default is referenced generically.

reference/cli/api-keys.mdx — Rename 'Principals: personal or
agent' → 'Personal vs. agent keys'. Replace 'Agent identities
power agent API keys' section with 'Cloud agents power agent
API keys' (1-2 sentences plus deploy-bot/pr-reviewer examples).
Delete 'The Default Service Account' section and its legacy
'team API key' callout entirely; the desktop-app creation step
gets one passing sentence about the **Team** toggle. Best
practices and Billing/GitHub-auth reframed around 'cloud agent
the key is bound to'.

Sweep across the rest of the PR's files (10 total):

- team-access-billing-and-identity.mdx: GitHub-auth step 3 and
  the Personal-tokens-vs-GitHub-App-tokens bullet drop
  'Default Service Account' and use 'cloud agent'.
- integrations/github-actions.mdx + quickstart-github-actions.mdx
  + reference/api-and-sdk/quickstart.mdx: drop the awkward
  '(no specific user behind them)' parenthetical; differentiate
  via attribution ('attribute runs to a cloud agent like
  `pr-reviewer`').
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
  managed-direct,unmanaged}.mdx: drop the explicit Default
  Service Account name; the team default is mentioned
  generically.
- external-authentication-required.mdx: 'bound to an agent
  identity' → 'bound to a cloud agent'.

Out of scope for this PR but flagged in the plan: secrets.mdx,
deployment-patterns.mdx, federate.mdx, cli/index.mdx use 'agent
identity' but were not touched here. Follow-up PR.

style_lint --changed shows 9 remaining warnings, all confirmed
false positives (one fewer than before since the Default
Service Account header was removed).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Drop bot-name examples and named-bot framing; cloud agents are characterized by their triggers

Address user feedback that:
1. deploy-bot / pr-reviewer / nightly-jobs examples were peppered everywhere
2. 'named bot' framing is wrong - a cloud agent is just an agent
   that runs in the cloud, characterized by its trigger
3. Docs shouldn't push the named-cloud-agent feature

Rewrites:

agents.mdx - Reframe entirely around triggers. The opening now
explains cloud agents as how Warp runs scheduled jobs,
integration triggers, CI/CD automation, and API-driven tasks.
'How cloud agents get triggered' replaces the value-prop bullets.
The 'Quickstart: create a custom agent identity' section is gone
- creating named cloud agents with attached secrets and skills
is an advanced configuration, not a headline feature. The
Managing cloud agents API reference stays for completeness.

api-keys.mdx - Simpler 'Personal vs. agent keys' framing:
- Personal: runs attributed to you
- Agent: runs as a cloud agent on your team, used for scheduled
  jobs, integrations, SDK-triggered runs, and other automation
  that isn't tied to a specific user
Dropped the entire 'Cloud agents power agent API keys' section
that listed name/secrets/skills as headline features. Best
practices no longer pushes 'pick a cloud agent that matches the
workflow'.

Sweep:
- github-actions.mdx, quickstart-github-actions.mdx: 'attribute
  runs to a cloud agent like pr-reviewer' \u2192 'run as a cloud
  agent on your team'
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
  managed-direct,unmanaged}.mdx: dropped 'use the team's default,
  or bind it to a custom cloud agent if you want the worker's
  runs attributed to a named bot' \u2192 just 'Create one in the Oz
  web app so the worker can authenticate'

All deploy-bot / pr-reviewer / nightly-jobs example names are now
removed from PR-touched files. Grep confirms no occurrences.

style_lint --changed: 8 false positives (down from 9 - the
deploy-bot UI-BACKTICK warning is gone).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Update src/content/docs/agent-platform/cloud-agents/agents.mdx

Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

* Address Rachael's review feedback

agents.mdx:
- Replace em-dash with period in default cloud agent paragraph
- Cross-link CLI and Warp app bullets to Oz CLI and cloud agents quickstart
- Remove ambiguous 'Cloud Mode' term in the Warp app bullet
- Clarify Service accounts section: 'authenticated as a service account'
- Restructure 'Managing cloud agents' with UI-first guidance, endpoint
  table, and separate caller-requirements list

api-keys.mdx:
- Name both key types explicitly ('personal API key' / 'agent API key')
- Update Oz web app procedure to match the live UI:
  - 'Generate new token' button label
  - 'Choose the type:' (matches the 'Type' label in the UI)
- Rename 'From the Warp desktop app' heading to 'From the Warp app'
- Replace 'Billing and GitHub authorization' section with parallel
  bullet lists under a more specific 'How key type affects billing and
  GitHub access' heading
- Split the managed-keys list so masked suffix, Created, and Last used
  are documented as Warp-app-only fields

Sidebar / cross-page consistency:
- Fix sidebar label from 'Agent identities' to 'Agents' so the nav
  matches the renamed page
- Update remaining 'agent identity' / 'Agent identities' references in
  oz-web-app.mdx, overview.mdx, deployment-patterns.mdx, secrets.mdx,
  reference/cli/index.mdx, and reference/cli/federate.mdx to 'cloud
  agent(s)' to match the new terminology

Co-Authored-By: Oz <oz-agent@warp.dev>

* Use 'Warp app' consistently in two remaining spots

Followup pass after Rachael's review: comment 3312118944 normalized the
heading to 'From the Warp app'. Two body sentences still read 'Warp
desktop app' — bring them in line with that wording.

- agents.mdx: 'Warp app' bullet body now says 'the Warp app' instead of
  'the Warp desktop app'.
- api-keys.mdx: 'Deleting API keys' section now says 'the Warp app's
  API Keys list' instead of 'the Warp desktop app's API Keys list'.

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: align agent UID wording + terminology + style guide (#168)

* docs: align agent UID OpenAPI wording

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: lint deprecated agent identity terminology

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>

* docs: address Ben's review feedback on cloud agents and API keys

- agents.mdx: reframe opening around giving automation its own settings/permissions; clarify when runs execute as a cloud agent vs the calling user (drop Warp app /cloud-agent bullet, which always runs as the user); convert endpoints HTML table to Markdown; remove the Team-scoped caller-requirement bullet
- self-hosting (managed-direct/docker/kubernetes, quickstart, reference): note the agent API key can be bound to any cloud agent and doesn't restrict which agents run on the worker
- unmanaged.mdx: 'agents' -> 'runs' are automatically team-scoped

Co-Authored-By: Oz <oz-agent@warp.dev>

* Update src/content/docs/reference/cli/api-keys.mdx

Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

* docs: terminology + description cleanup from audit pass

- bring-your-own-llm.mdx: 'agent identity' -> 'cloud agent' (term carried in from main)
- agents.mdx: reframe frontmatter description to match the reworked opening (own settings/permissions vs acting as a user)

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: keep original cloud agents page description

Revert the frontmatter description change from the audit pass per preference; the reworked body opening is unchanged.

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

* Document Personal / Team / Agent API key types

The Oz web app at oz.warp.dev/settings now uses 'Agent' API keys bound
to a specific agent identity, while the Warp desktop app still shows
'Team' (an Agent key bound to the team's Default Service Account is
functionally identical to a Team key for headless workflows).

Updates:
- reference/cli/api-keys.mdx: rewrite to cover all three key types,
  describe per-surface UI (Oz web app vs. Warp desktop app), and call
  out the Default Service Account / Team-key equivalence.
- Self-hosting prereqs (managed-{docker,kubernetes,direct}, quickstart,
  unmanaged), integrations/quickstart-github-actions, api-and-sdk/
  quickstart, reference/cli/quickstart: update 'create a team API key'
  wording to mention both surfaces and link the new key-types section.
- integrations/github-actions.mdx: replace broken /reference/cli/
  #generating-api-keys anchor with /reference/cli/api-keys/.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Broaden API key wording across billing, GitHub auth, and error docs

After auditing PR warpdotdev#141 (parallel Codex run for REMOTE-1777), extend the
sweep to the files that still said 'team API key' in places where the
phrase should also acknowledge agent identity / Default Service Account
keys created in the Oz web app. The Warp desktop app continues to label
its key type 'Team' (and Jason is reverting NamedAgents in the client
so it stays that way), so the wording becomes 'team or agent API key'
rather than a pure rename.

Touched files:
- agent-platform/cloud-agents/agents.mdx
- agent-platform/cloud-agents/team-access-billing-and-identity.mdx
- agent-platform/cloud-agents/environments.mdx
- agent-platform/cloud-agents/quickstart.mdx
- agent-platform/cloud-agents/self-hosting/reference.mdx
- enterprise/team-management/admin-panel.mdx
- enterprise/support-and-resources/billing.mdx
- reference/cli/integration-setup.mdx
- reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx
- reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx
- support-and-community/plans-and-billing/credits.mdx
- support-and-community/plans-and-billing/add-on-credits.mdx
- support-and-community/plans-and-billing/pricing-faqs.mdx

agents.mdx also gains the explicit 'Default Service Account' callout
and the Warp-app-Team / Oz-web-app-Agent equivalence note.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Final pass: normalize key-type casing, remove redundant Enterprise sentence

After a final review, polish the wording for consistency:

- Lowercase 'team API key' / 'agent API key' in prose (the concept).
  Reserve **bold** for the literal UI labels (Personal / Team / Agent).
  This matches how 'personal API key' was already styled.
- Self-hosting prereqs: switch (`Agent` type) / (`Team` type) backticks
  to (**Agent** type) / (**Team** type) since these are UI labels per the
  style guide, not literal code/strings.
- agents.mdx: 'called **Default Service Account**' → backticks, to match
  every other reference to the identity name in this PR.
- team-access-billing-and-identity.mdx line 85: drop a redundant
  'On Enterprise plans, these runs draw from the team-scoped credit
  pool...' sentence I had accidentally added to the Build/Max/Business
  bullet — that case is already covered by the Enterprise bullet right
  below it, and the GitHub-auth note duplicates content from the
  dedicated 'Team GitHub authorization' section.
- api-keys.mdx 'Deleting API keys' wording: 'find it in either surface'
  was ambiguous; spell it out as 'either the Oz web app or the Warp
  desktop app's API Keys list'.

No structural changes — pure textual edits, build behavior unchanged.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Switch to 'agent API key' throughout, with single team\u2192agent disclaimer

Per user feedback: stop dual-naming (team or agent API key) and just use
'agent API key' everywhere. Add a single, prominent disclaimer at the
top of api-keys.mdx noting that 'agent' used to be called 'team' and
that the two behave identically.

api-keys.mdx restructured:
- Top of page: new :::note 'Naming change' disclaimer that explains the
  team \u2192 agent rename, the Default Service Account equivalence, and
  notes the Warp desktop app may still label the toggle 'Team'.
- 'API key types' section: now lists only Personal and Agent (Team
  folded into Agent with the legacy-key note).
- 'Creating API keys > From the Warp desktop app': simplified to a
  single step that says pick Personal, Agent, or Team; pointers back
  to the disclaimer for details.\n- Best practices and Managing sections: 'team or agent keys' \u2192\n  'agent keys'.\n\nAll other affected files: 'team or agent API key' / 'team and agent\nAPI key' / pre-existing 'team API key' \u2192 'agent API key'. The legacy\nterm only survives in:\n- The api-keys.mdx disclaimer.\n- One parenthetical in team-access-billing-and-identity.mdx that\n  explicitly explains the legacy term for users who see it in the\n  Warp desktop app.\n- analytics-api.mdx now says 'Agent API keys (including legacy team\n  keys) are explicitly rejected'.\n- A historical changelog entry.\n\nCo-Authored-By: Oz <oz-agent@warp.dev>

* Reframe agent API key docs around agent identities

Restructure the API keys page (reference/cli/api-keys.mdx) so it reads
as a principal-first conceptual page:

- Open with 'Principals: personal or agent' instead of leading with
  the legacy naming-change disclaimer.
- Add 'Agent identities power agent API keys' with concrete worked
  examples (deploy-bot, pr-reviewer, nightly-jobs) that show how
  binding a key to an identity scopes its secrets, skills, and
  attribution.
- Add 'The Default Service Account' as the no-config baseline, and
  house the legacy 'team API key' note there as an inline callout.
- Split 'Creating an API key' into Oz web app (recommended, only
  surface that exposes the named-identity picker) and Warp desktop
  app (binds agent keys to the Default Service Account).
- Reframe billing and GitHub-authorization around the principal.

Strengthen agents.mdx (the agent-identity concept page):

- Add an IAM-service-account mental model paragraph.
- Strengthen the value-prop bullets with concrete deploy-bot /
  pr-reviewer / nightly-jobs examples.
- Add 'Quickstart: create a custom agent identity' (5 steps:
  create secret, POST /api/v1/agent/identities, generate bound key,
  run agent, confirm attribution in the dashboard).
- Add a short 'Agent API keys' subsection cross-linking to
  api-keys.mdx and naming the legacy 'team API key' equivalence.

Tighten the other affected docs so they defer to api-keys.mdx for
the personal-vs-agent guidance instead of repeating per-line
'Warp desktop app's equivalent toggle may still show Team' notes:

- self-hosting/{quickstart,managed-{docker,kubernetes,direct},
  unmanaged}.mdx prereqs collapse to 'Create an agent API key in
  the Oz web app bound to the Default Service Account (or a custom
  agent identity for workflow-scoped attribution).'
- team-access-billing-and-identity.mdx GitHub-auth section
  attributes commits to the bound agent identity (or to the
  Default Service Account for legacy team keys).
- integrations/github-actions.mdx, integrations/quickstart-github-actions.mdx,
  reference/api-and-sdk/quickstart.mdx, reference/cli/quickstart.mdx
  shorten inline notes to point at api-keys.mdx and link agents.mdx.
- unmanaged.mdx: wrap the oz agent run CLI command in backticks in
  the description so it reads as a literal command (also clears the
  OZ-TERM style lint warning).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Disentangle GitHub-side commit attribution from Oz-side run identity

Addresses oz-for-oss review on PR warpdotdev#143 (discussion r3307282172): the
docs incorrectly claimed that PRs and commits opened via the Oz by
Warp GitHub App were attributed to the bound agent identity. In
reality:

- On GitHub, commits and pull requests opened with a GitHub App
  installation token are attributed to the Oz by Warp GitHub App's
  bot user — not to the agent identity the API key is bound to.
- The agent identity is the Oz-side run identity. It controls run
  filtering, audit attribution, and which secrets/skills the run
  inherits — but it does not appear as a commit author on GitHub.

Fix the three places that had the conflation:

- team-access-billing-and-identity.mdx "Setting up team GitHub
  authorization" step 3 (line 143).
- team-access-billing-and-identity.mdx "Personal tokens vs. GitHub
  App tokens" bullet (line 159).
- reference/cli/api-keys.mdx "Billing and GitHub authorization"
  agent-keys paragraph (line 82).

Each now explicitly separates 'on GitHub, the GitHub App is the
author' from 'in the Oz dashboard, the agent identity is the run
attribution'.

The companion SUGGESTION (r3307282159) about the billing bullet at
team-access-billing-and-identity.mdx line 85 was already addressed
by the earlier restructure commit 51ea888 — that bullet no longer
duplicates the Enterprise sentence or mixes GitHub authorization
into the billing-focused list. The 'Team or' prefix in the
reviewer's suggested wording is intentionally not adopted, because
the restructure unifies the terminology under 'agent API key'
(with the legacy 'team API key' equivalence covered once in
api-keys.mdx#the-default-service-account).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Replace 'headless' / 'workflow-scoped' jargon with plain 'automated'

Per feedback that 'workflow-scoped identity for headless runs' is
hard to parse, sweep the PR's affected files and replace jargon
with plain-English equivalents:

- 'workflow-scoped identity for headless runs' \u2192 'automated runs
  (no specific user behind them)' or 'automated runs' depending
  on context.
- 'headless run / workflow / caller / automation' \u2192 'automated
  run / workflow / caller'.
- 'workflow-scoped attribution' \u2192 'so runs are attributed to a
  specific bot'.

Files touched: integrations/github-actions.mdx,
integrations/quickstart-github-actions.mdx, reference/cli/api-keys.mdx
(Principals, Default Service Account, Creating an API key from the
Oz web app, Best practices), agents.mdx (mental-model paragraph,
How agent identities work, Agent API keys, Running as an agent
identity), reference/api-and-sdk/quickstart.mdx,
self-hosting/unmanaged.mdx, team-access-billing-and-identity.mdx
(credit usage bullet).

Kept the industry-standard term 'headless servers' in the
api-keys.mdx opening line (CI pipelines, headless servers, VMs,
Codespaces) since that's a well-understood compound term.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Senior copywriter pass: rename to 'cloud agents', drop Default Service Account, fix principal differentiation

Address user feedback on the prior framing:

1. "agent identity" sounds abstract; just call them cloud agents
2. "Default Service Account" is an internal implementation detail
3. "(no specific user behind them)" is an awkward way to differentiate

Major rewrites:

agents.mdx — Rename to 'Agents'. Drop the IAM service account
analogy. Open with what a cloud agent is and what binding a key
to it gets you. Replace every 'agent identity'/'identities'
with 'cloud agent'/'cloud agents' (or just 'agent' when
unambiguous). Drop standalone 'Default Service Account'
mentions; the team default is referenced generically.

reference/cli/api-keys.mdx — Rename 'Principals: personal or
agent' → 'Personal vs. agent keys'. Replace 'Agent identities
power agent API keys' section with 'Cloud agents power agent
API keys' (1-2 sentences plus deploy-bot/pr-reviewer examples).
Delete 'The Default Service Account' section and its legacy
'team API key' callout entirely; the desktop-app creation step
gets one passing sentence about the **Team** toggle. Best
practices and Billing/GitHub-auth reframed around 'cloud agent
the key is bound to'.

Sweep across the rest of the PR's files (10 total):

- team-access-billing-and-identity.mdx: GitHub-auth step 3 and
  the Personal-tokens-vs-GitHub-App-tokens bullet drop
  'Default Service Account' and use 'cloud agent'.
- integrations/github-actions.mdx + quickstart-github-actions.mdx
  + reference/api-and-sdk/quickstart.mdx: drop the awkward
  '(no specific user behind them)' parenthetical; differentiate
  via attribution ('attribute runs to a cloud agent like
  `pr-reviewer`').
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
  managed-direct,unmanaged}.mdx: drop the explicit Default
  Service Account name; the team default is mentioned
  generically.
- external-authentication-required.mdx: 'bound to an agent
  identity' → 'bound to a cloud agent'.

Out of scope for this PR but flagged in the plan: secrets.mdx,
deployment-patterns.mdx, federate.mdx, cli/index.mdx use 'agent
identity' but were not touched here. Follow-up PR.

style_lint --changed shows 9 remaining warnings, all confirmed
false positives (one fewer than before since the Default
Service Account header was removed).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Drop bot-name examples and named-bot framing; cloud agents are characterized by their triggers

Address user feedback that:
1. deploy-bot / pr-reviewer / nightly-jobs examples were peppered everywhere
2. 'named bot' framing is wrong - a cloud agent is just an agent
   that runs in the cloud, characterized by its trigger
3. Docs shouldn't push the named-cloud-agent feature

Rewrites:

agents.mdx - Reframe entirely around triggers. The opening now
explains cloud agents as how Warp runs scheduled jobs,
integration triggers, CI/CD automation, and API-driven tasks.
'How cloud agents get triggered' replaces the value-prop bullets.
The 'Quickstart: create a custom agent identity' section is gone
- creating named cloud agents with attached secrets and skills
is an advanced configuration, not a headline feature. The
Managing cloud agents API reference stays for completeness.

api-keys.mdx - Simpler 'Personal vs. agent keys' framing:
- Personal: runs attributed to you
- Agent: runs as a cloud agent on your team, used for scheduled
  jobs, integrations, SDK-triggered runs, and other automation
  that isn't tied to a specific user
Dropped the entire 'Cloud agents power agent API keys' section
that listed name/secrets/skills as headline features. Best
practices no longer pushes 'pick a cloud agent that matches the
workflow'.

Sweep:
- github-actions.mdx, quickstart-github-actions.mdx: 'attribute
  runs to a cloud agent like pr-reviewer' \u2192 'run as a cloud
  agent on your team'
- self-hosting/{quickstart,managed-docker,managed-kubernetes,
  managed-direct,unmanaged}.mdx: dropped 'use the team's default,
  or bind it to a custom cloud agent if you want the worker's
  runs attributed to a named bot' \u2192 just 'Create one in the Oz
  web app so the worker can authenticate'

All deploy-bot / pr-reviewer / nightly-jobs example names are now
removed from PR-touched files. Grep confirms no occurrences.

style_lint --changed: 8 false positives (down from 9 - the
deploy-bot UI-BACKTICK warning is gone).

Co-Authored-By: Oz <oz-agent@warp.dev>

* Update src/content/docs/agent-platform/cloud-agents/agents.mdx

Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

* Address Rachael's review feedback

agents.mdx:
- Replace em-dash with period in default cloud agent paragraph
- Cross-link CLI and Warp app bullets to Oz CLI and cloud agents quickstart
- Remove ambiguous 'Cloud Mode' term in the Warp app bullet
- Clarify Service accounts section: 'authenticated as a service account'
- Restructure 'Managing cloud agents' with UI-first guidance, endpoint
  table, and separate caller-requirements list

api-keys.mdx:
- Name both key types explicitly ('personal API key' / 'agent API key')
- Update Oz web app procedure to match the live UI:
  - 'Generate new token' button label
  - 'Choose the type:' (matches the 'Type' label in the UI)
- Rename 'From the Warp desktop app' heading to 'From the Warp app'
- Replace 'Billing and GitHub authorization' section with parallel
  bullet lists under a more specific 'How key type affects billing and
  GitHub access' heading
- Split the managed-keys list so masked suffix, Created, and Last used
  are documented as Warp-app-only fields

Sidebar / cross-page consistency:
- Fix sidebar label from 'Agent identities' to 'Agents' so the nav
  matches the renamed page
- Update remaining 'agent identity' / 'Agent identities' references in
  oz-web-app.mdx, overview.mdx, deployment-patterns.mdx, secrets.mdx,
  reference/cli/index.mdx, and reference/cli/federate.mdx to 'cloud
  agent(s)' to match the new terminology

Co-Authored-By: Oz <oz-agent@warp.dev>

* Use 'Warp app' consistently in two remaining spots

Followup pass after Rachael's review: comment 3312118944 normalized the
heading to 'From the Warp app'. Two body sentences still read 'Warp
desktop app' — bring them in line with that wording.

- agents.mdx: 'Warp app' bullet body now says 'the Warp app' instead of
  'the Warp desktop app'.
- api-keys.mdx: 'Deleting API keys' section now says 'the Warp app's
  API Keys list' instead of 'the Warp desktop app's API Keys list'.

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: align agent UID wording + terminology + style guide (warpdotdev#168)

* docs: align agent UID OpenAPI wording

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: lint deprecated agent identity terminology

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>

* docs: address Ben's review feedback on cloud agents and API keys

- agents.mdx: reframe opening around giving automation its own settings/permissions; clarify when runs execute as a cloud agent vs the calling user (drop Warp app /cloud-agent bullet, which always runs as the user); convert endpoints HTML table to Markdown; remove the Team-scoped caller-requirement bullet
- self-hosting (managed-direct/docker/kubernetes, quickstart, reference): note the agent API key can be bound to any cloud agent and doesn't restrict which agents run on the worker
- unmanaged.mdx: 'agents' -> 'runs' are automatically team-scoped

Co-Authored-By: Oz <oz-agent@warp.dev>

* Update src/content/docs/reference/cli/api-keys.mdx

Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

* docs: terminology + description cleanup from audit pass

- bring-your-own-llm.mdx: 'agent identity' -> 'cloud agent' (term carried in from main)
- agents.mdx: reframe frontmatter description to match the reworked opening (own settings/permissions vs acting as a user)

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs: keep original cloud agents page description

Revert the frontmatter description change from the audit pass per preference; the reworked body opening is unchanged.

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>